/*-------------------------------------------------------------------------
 |   RXTX License v 2.1 - LGPL v 2.1 + Linking Over Controlled Interface.
 |   RXTX is a native interface to serial ports in java.
 |   Copyright 1997-2007 by Trent Jarvi tjarvi@qbang.org and others who
 |   actually wrote it.  See individual source files for more information.
 |
 |   A copy of the LGPL v 2.1 may be found at
 |   http://www.gnu.org/licenses/lgpl.txt on March 4th 2007.  A copy is
 |   here for your convenience.
 |
 |   This library is free software; you can redistribute it and/or
 |   modify it under the terms of the GNU Lesser General Public
 |   License as published by the Free Software Foundation; either
 |   version 2.1 of the License, or (at your option) any later version.
 |
 |   This library is distributed in the hope that it will be useful,
 |   but WITHOUT ANY WARRANTY; without even the implied warranty of
 |   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 |   Lesser General Public License for more details.
 |
 |   An executable that contains no derivative of any portion of RXTX, but
 |   is designed to work with RXTX by being dynamically linked with it,
 |   is considered a "work that uses the Library" subject to the terms and
 |   conditions of the GNU Lesser General Public License.
 |
 |   The following has been added to the RXTX License to remove
 |   any confusion about linking to RXTX.   We want to allow in part what
 |   section 5, paragraph 2 of the LGPL does not permit in the special
 |   case of linking over a controlled interface.  The intent is to add a
 |   Java Specification Request or standards body defined interface in the 
 |   future as another exception but one is not currently available.
 |
 |   http://www.fsf.org/licenses/gpl-faq.html#LinkingOverControlledInterface
 |
 |   As a special exception, the copyright holders of RXTX give you
 |   permission to link RXTX with independent modules that communicate with
 |   RXTX solely through the Sun Microsytems CommAPI interface version 2,
 |   regardless of the license terms of these independent modules, and to copy
 |   and distribute the resulting combined work under terms of your choice,
 |   provided that every copy of the combined work is accompanied by a complete
 |   copy of the source code of RXTX (the version of RXTX used to produce the
 |   combined work), being distributed under the terms of the GNU Lesser General
 |   Public License plus this exception.  An independent module is a
 |   module which is not derived from or based on RXTX.
 |
 |   Note that people who make modified versions of RXTX are not obligated
 |   to grant this special exception for their modified versions; it is
 |   their choice whether to do so.  The GNU Lesser General Public License
 |   gives permission to release a modified version without this exception; this
 |   exception also makes it possible to release a modified version which
 |   carries forward this exception.
 |
 |   You should have received a copy of the GNU Lesser General Public
 |   License along with this library; if not, write to the Free
 |   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 |   All trademarks belong to their respective owners.
 --------------------------------------------------------------------------*/
package gnu.io;

import java.util.*;

/**
 * The <code>CommPortOwnershipListener</code> is an observer interface which
 * keeps track of the ownership of a port.
 *
 * The listener must be registered on a port via
 * <code>CommPortIdentiefer.addPortOwnershipListener()</code> first. Then it is
 * notified when other applications try to access the port or the ownership
 * changes.
 *
 * @author Trent Jarvi
 * @version 2.2
 * @since JDK1.0
 */
public interface CommPortOwnershipListener extends EventListener {

    /**
     * The port is owned by an application.
     */
    public static final int PORT_OWNED = 1;
    /**
     * The pot is not owned by an application and is ready to be opened.
     */
    public static final int PORT_UNOWNED = 2;
    /**
     * Another application requests to open the port. If this application
     * receives this event while holding the port and wants to give ownership to
     * the requesting application, then <code>CommPort.close()</code> should be
     * called as fast as possible.
     */
    public static final int PORT_OWNERSHIP_REQUESTED = 3;

    /**
     * Receives change notifications about the port ownership.
     *
     * @param type one of the <code>PORT_*</code> constants indicating the
     * notification type.
     */
    //TODO (by Alexander Graf): it would be nice to get the port identifier on
    // which the ownership event occured. This would enable us to register a
    // single listener implementation on multiple port identifiers
    public abstract void ownershipChange(int type);
}
